home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / c / AMesaRTL.lha / Mesa-2.6 / amiga / drivers / mesadriver.doc
Text File  |  1998-09-19  |  22KB  |  629 lines
  1. TABLE OF CONTENTS
  2.  
  3. mesadriver/--background--
  4. mesadriver/AmigaMesaRTLCreateContextA
  5. mesadriver/AmigaMesaRTLDestroyContext
  6. mesadriver/AmigaMesaRTLMakeCurrent
  7. mesadriver/AmigaMesaRTLGetCurrentContext
  8. mesadriver/AmigaMesaRTLSetIndexRGBTable
  9. mesadriver/AmigaMesaRTLSetIndexRGB
  10. mesadriver/AmigaMesaRTLGetIndexRGB
  11. mesadriver/AmigaMesaRTLSetContextAttrsA
  12. mesadriver/AmigaMesaRTLGetContextAttr
  13. mesadriver/AmigaMesaRTLSetOutputHandlerAttrsA
  14. mesadriver/AmigaMesaRTLGetOutputHandlerAttr
  15. mesadriver/AmigaMesaRTLSetAttrsA
  16. mesadriver/AmigaMesaRTLGetAttr
  17.  
  18. mesadriver/--background--                           mesadriver/--background--
  19.  
  20.    NAME
  21.         mesadriver - Driver interface to AmigaMesaRTL
  22.  
  23.    PURPOSE
  24.         This document describes the Amiga-specific interface to the Mesa
  25.         library.
  26.  
  27.         The driver is what makes Mesa work on a specific platform. It
  28.         provides the low-level operations, such as drawing a pixel, which
  29.         the main Mesa library eventually calls to produce output. These
  30.         functions are for use by the Mesa library alone, and so are not
  31.         publicly accessible.
  32.  
  33.         The driver also provides the platform-specific routines needed to set
  34.         up and manage a context. These functions are publicly accessible of
  35.         course, and are described here.
  36.         
  37.         Mesa has two modes: Index mode and RGBA mode. In Index mode, the
  38.         buffer contains one byte per pixel. Each byte is an index into a
  39.         palette table describing the colour of that pixel.
  40.         
  41.         In RGBA mode, the buffer contains four bytes per pixel, describing
  42.         the truecolour colour of the pixel. The order of the bytes in the
  43.         buffer is of no concern to the user, only to the driver and output
  44.         handler. The output handler can tell the driver what order to use by
  45.         implementing the OH_RGBAOrder tag (see the outputhandler doc). The
  46.         AmigaMesaRTL driver understands both RGBA (A in lowbyte) and ARGB (A
  47.         in highbyte) order, and defaults to RGBA.
  48.  
  49.    WRITING YOUR OWN DRIVER
  50.         Any driver should at least present the interface described here. A
  51.         driver need not support output handlers.
  52.  
  53.         The Mesa library makes heavy use of function pointers. This presents
  54.         a problem, as functions in an Amiga run-time library expect a pointer
  55.         to the library base in register A6, which is not set up when the
  56.         function is called through a function pointer. This alone is not
  57.         disasterous. But the global data pointer A4 is determined based on
  58.         the value of A6 if the library is linked with libinitr.o. Fortunately
  59.         very few functions are likely to need access to the global data
  60.         section. In the case of the AmigaMesaRTL driver, only get_buffer_size
  61.         and renderer_string need to. In the former case, A4 is manually set
  62.         to a value stored in the context. In the latter case, the constant
  63.         string is actually put in the far data section, which is shared by
  64.         all instances of the library.
  65.  
  66. mesadriver/AmigaMesaRTLCreateContextA   mesadriver/AmigaMesaRTLCreateContextA
  67.  
  68.    NAME
  69.         AmigaMesaRTLCreateContextA - Create a new context
  70.         AmigaMesaRTLCreateContext - Varargs stub
  71.  
  72.    SYNOPSIS
  73.         result = AmigaMesaRTLCreateContextA(tags)
  74.         D0                                  A0
  75.  
  76.         AmigaMesaRTLContext AmigaMesaRTLCreateContextA(struct TagItem *);
  77.  
  78.         result = AmigaMesaRTLCreateContext(tag1, ...)
  79.  
  80.         AmigaMesaRTLContext AmigaMesaRTLCreateContext(ULONG, ...);
  81.  
  82.    FUNCTION
  83.         A new Mesa rendering context is created and initialized. If requested
  84.         an output handler is also opened and initialized. Don't assume that
  85.         the context will be current after creation.
  86.  
  87.    INPUTS
  88.         tags - Pointer to a tag list
  89.  
  90.    TAGS
  91.         AMRTL_RGBAMode (BOOL) - Use RGBA mode. (Default TRUE)
  92.  
  93.         AMRTL_IndexMode (BOOL) - Use Index mode. (Default FALSE)
  94.  
  95.         AMRTL_OutputHandler (STRPTR) - Name of output handler to use. If the
  96.              tag value is NULL, no output handler is opened unless the tag
  97.              AMRTL_OutputHandlerBase is also used.
  98.  
  99.         AMRTL_OutputHandlerVersion (ULONG) - Lowest version number to request
  100.              when opening an output handler. The default is given by the
  101.              environment variable "AmigaMesaRTL/OutputHandlerVersion", or 2
  102.              if that does not exist either.
  103.  
  104.         AMRTL_OutputHandlerBase (struct Library *) - Use the given output
  105.              handler library base instead of opening a new one. If the tag
  106.              value is NULL, no output handler will be opened.
  107.  
  108.              If neither AMRTL_OutputHandler nor AMRTL_OutputHandlerBase are
  109.              given, environment variables are used to determine which handler
  110.              to open. If an output type is specified (OH_OutputType) in the
  111.              tag list, the output handler named in the environment variable
  112.              "AmigaMesaRTL/<output type>" is used. If variable can not be
  113.              used, the default handler named in the environment variable
  114.              "AmigaMesaRTL/OutputHandler" is used. If this doesn't exist
  115.              either, the dl1 output handler is used.
  116.  
  117.         AMRTL_Mode (ULONG) - What mode to use. Currently only AMRTL_RGBAMode
  118.              and AMRTL_IndexMode are valid valued for this tag. (Default
  119.              AMRTL_RGBAMode).
  120.  
  121.         AMRTL_OutputWidth (GLint)
  122.         AMRTL_OutputHeight (GLint) - Initial requested size of the output
  123.              buffer. This value may be overridden by the output handler, and
  124.              modified by the driver. (Defaults 8).
  125.  
  126.         AMRTL_GL (STRPTR) - Name of the main mesa library to use. The driver
  127.              must know which mesa library to use. Both the program using the
  128.              driver and the driver itself must use the same Mesa library
  129.              base, so if you specify this tag, your program must get the
  130.              value of the AMRTL_GLBase tag and use it as the mesamainBase.
  131.              At present the mesa base can be and must be set only once for a
  132.              given mesadriverBase. If you link with Mesa.LIB, this will be
  133.              done by the autoinitialization function, so this tag will be
  134.              ignored. Note that it is a Bad Idea to share the same mesa main
  135.              base with other mesa driver bases.
  136.  
  137.         AMRTL_GLBase (struct Library *) - Similar to AMRTL_GL, except you
  138.              pass an already-opened mesamainBase pointer.
  139.  
  140.         OH_#? - If an output handler is used, it will be initialized with a
  141.              copy of the tag list used to create the context. You can
  142.              therefore also specify output handler tags here for output
  143.              handler initialization. The driver will set OH_DriverBase.
  144.  
  145.    RESULTS
  146.         result - An abstract AmigaMesaRTLContext pointer, or NULL if an error
  147.                  occured during initialization.
  148.  
  149.    BUGS
  150.         None
  151.  
  152.    SEE ALSO
  153.         AmigaMesaRTLDestroyContext()
  154.  
  155.  
  156. mesadriver/AmigaMesaRTLDestroyContext   mesadriver/AmigaMesaRTLDestroyContext
  157.  
  158.    NAME
  159.         AmigaMesaRTLDestroyContext - Delete a context
  160.  
  161.    SYNOPSIS
  162.         AmigaMesaRTLDestroyContext(context)
  163.                                    A0
  164.  
  165.         void AmigaMesaRTLDestroyContext(AmigaMesaRTLContext);
  166.  
  167.    FUNCTION
  168.         The given context is deleted. If an output handler is associated with
  169.         the context, it too is deleted. If the driver opened the handler, the
  170.         handler is closed as well.
  171.  
  172.    INPUTS
  173.         context - Context to delete
  174.  
  175.    RESULTS
  176.         None
  177.  
  178.    BUGS
  179.         None
  180.  
  181.    SEE ALSO
  182.  
  183.  
  184. mesadriver/AmigaMesaRTLMakeCurrent         mesadriver/AmigaMesaRTLMakeCurrent
  185.  
  186.    NAME
  187.         AmigaMesaRTLMakeCurrent - Make a context current
  188.  
  189.    SYNOPSIS
  190.         AmigaMesaRTLMakeCurrent(context)
  191.                                 A0
  192.  
  193.         void AmigaMesaRTLMakeCurrent(AmigaMesaRTLContext);
  194.  
  195.    FUNCTION
  196.         The given context is made current. A context must be made current if
  197.         you want to do anything with it. Failure to do so will cause very
  198.         strange things to happen.
  199.  
  200.    INPUTS
  201.         context - Context to make current
  202.  
  203.    RESULTS
  204.         None
  205.  
  206.    BUGS